BBS Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ BBS Toolkit / BBS Toolkit.iso / programs / znews093.zip / ZIPNEWS.DOC < prev next >

Wrap

Text File | 1993-01-20 | 18KB | 360 lines

ZipNews v0.93ß (1/20/93) (c) Copyright 1993 by J.C. Kilday Associates Developed at the Northern Lights BBS 207-761-4782 v.32bis/VHST Table of Contents ----------------- Introduction ..................... 1 Description ...................... 2 Installation Overview ............ 2 Installation Details ............. 3 Operating/Using ZipNews .......... 4 Distribution and Restrictions .... 5 After You Register ZipNews ....... 5 Support .......................... 6 ZipNews v0.93ß Page 1 Introduction ------------ ZipNews is an external command for use with the DOS-based Waffle BBS package. It operates much like a Door in that it reacts interactively to caller input as an extension of the BBS software. It's purpose is fast delivery of Usenet news articles for offline reading. It greatly simplifies the process of reading Usenet news by allowing the caller to download new postings in compressed form for reading offline. In accomplishing this, ZipNews allows a broad selection of DOS-based archiving utilities for compressing the news packet and it supports a variety of file transfer protocols (use of Forsberg's DSZ package is recommended). The selection of archiving utilities and protocols is determined by the system operator. The individual command line specifications are also established by the system operator using a configuration text file. A sample configuration file is included in this package. First-time users entering the ZipNews Door are prompted to establish their personal choices of archive utility and file transfer protocol. User choices are maintained for subsequent calls by the system. If download of a news packet is requested, the user is presented an active display indicating the newsgroups being scanned, the number of articles being extracted, and other progress information. At the conclusion of the scan, the user has the option of NOT accepting the packet and returning to the Waffle system to alter groups JOINed, etc. Once the user affirms that an assembled packet should be sent, the packet is compressed and the transfer of the resulting file is initiated. If the normal process is interrupted before a successful conclusion, the "last article read" pointers in the user's JOIN file are restored to their previous settings. Otherwise, upon a successful download, these pointers are appropriately updated. (Note: this operation is dependent upon the archiver and protocol modules returning appropriate "success/fail" DOS ERRORLEVELs. Utilities such as PKZIP and DSZ are known to work correctly in this regard.) ZipNews is SHARE-compatible and can support multi-node operations from a single configuration file (ZN.CFG). It can handle non-standard comm port specifications and speeds to 38,400 bps. FOSSIL communications are not used. ZipNews disables FOSSIL supported comm when run, but FOSSIL support is "reset" per the normal way when returning to Waffle. ZipNews is being distributed as a fully functional package (not crippled in any way). In its unregistered form, ZipNews DOES display on-screen, and in the files produced, notices informing system operators and users that it is an unregistered, evaluation copy. The executable is self-registering in that when a valid registration number is input these notices are removed and, thereafter, the registrant's name is displayed. The complete ZipNews v0.93ß package includes the following files: ZIPNEWS.DOC - this file ZN.COM - executable module ZN.CFG - sample ZipNews configuration file ZIPNEWS - the Waffle external command file for ZipNews ZNORDER.FRM - order form for registering ZipNews READ.ME - quick review and features summary ZipNews v0.93ß Page 2 Description ----------- ZipNews is designed for operation on MS-DOS 3.O and later systems. Operation with earlier DOS versions is not supported. ZipNews is distributed as a small .COM executable so as to minimize RAM requirements during operation (necessary, as it remains in memory when archiving utilities and protocol modules are invoked). It is being released initially while in its final BETA test stages. There may be a few minor additional features incorporated in the first "official" release. (See the READ.ME file included in this package.) Zipnews has been tested primarily in a DOS 5.0/DESQview environment, on a system running 4 nodes (PCBoard as primary BBS and Waffle 1.65 as a Door). It has not been tested with other versions of Waffle. Installation Overview --------------------- This section quickly suumarizes the major steps in setting up. The next section covers installation in greater detail. 1. Place ZN.COM and the sample ZN.CFG into a directory in your PATH (\waffle\bin will do quite nicely). 2. Customize ZN.CFG as needed using an ASCII text editor. This also involves naming and specifying command lines for archive utilities and file tranfer protocols you wish to make available to callers. 3. Make (or modify) the ZIPNEWS external command file and place it in your \waffle\external directory. 4. Provide for setting the required DOS ENVIRONMENT variables. A very important one is the DSZPORT variable. 5. If running a multi-node system, provide for uniquely named work directories (one for each node) for temporary file storage. This will require an environment variable also. 6. If running a multi-node system, set the read-only (write protect) file attribute bit on ZN.COM (avoids SHARE violations while program loading during normal multi-node operations). Installation Details -------------------- ZipNews (ZN.COM) should be placed in a directory contained in your DOS PATH (e.g., \waffle\bin). Your ZipNews configuration file (ZN.CFG) should be placed in the same directory. WARNING: ZN.COM locates the directory in which it resides, no matter how started, and you MUST(!) have ZN.CFG located in that same directory for proper operation. Your ZIPNEWS external command file should be quite similar to that provided as part of this package. It should be placed in your \waffle\external directory (on Waffle v1.65 systems). An example of this one-line file appears below: zipnews /local /reset /command="d:\waffle\bin\zn %A" Note that the only command line parm required on startup is the Waffle account (caller's ID). ZipNews v0.93ß Page 3 To configure ZipNews to your system, use a standard ASCII text editor to modify the ZN.CFG provided. The basic format rules are: 1) Lines beginning with a space or a # symbol are ignored. 2) The 8 configuration subject titles listed below MUST be present in the finished .CFG file and each must be followed by a colon (:). There MAY be intervening whitespace. newsgroups user temporary bbs abbrev maximum archivers protocols 3) The lines may be in any order, but the sub-lines for archivers and protocols must be grouped within their respective sections, and with the "prompt" lines immediately preceding the corresponding command line specifications. 4) The command lines for the protocols contain one character in the first position which is not a part of the command line. This is the "selection character", that by which a caller may express his/her protocol choice. Additional conventions used in the ZN.CFG file follow. If you need to specify more than one top level news directory on your system, indicate the full pathname to each (without a trailing "\") and with a space separating each pathname. If you have sufficient RAM available for use of a RAMDISK, such is heartily recommended -- not only for speed gains, but for preventing wear and tear on your hard drive. However, you may name a hard disk and directory in the "temporary" parameter as your work directory. This is the directory in which the extracted news articles are placed and compressed for download. If you are running a multi-node system, you will need to specify multiple temporary work directories (one for each node) using this parameter . Here's how to do it: 1) Set an ENVIRONMENT variable for each node. In each node's ENVIRONMENT a new variable should be defined, NODE, for example. Assign the number of the node to each one as required. Thus in the ENVIRONMENT controlling node 1, you would set NODE=1, for node 2, NODE=2 , etc. 2) Specify your "temporary" parameter such that it contains the variable name with a % before and after it (just as in DOS batch files). So you might specify in your ZN.CFG line: temporary : g:\work%node% This would be interpreted by ZipNews running on node 1 as g:\work1, on node 2 as g:\work2, etc. This method will allow you to run any number of BBS nodes from a single copy of ZN.COM and ZN.CFG. ZipNews v0.93ß Page 4 It is recommended that Forsberg's ubiquitous DSZ protocol module be used to support file transfers. In fact, ZipNews has not been tested with any other. Normally protocol modules must have the comm port and speed communicated to them when invoked. DSZ automatically determines the speed, so this spec is not necessary. To specify the comm port number, or to specify a non-standard comm port, you set the DSZPORT environment variable. (Set DSZPORT=1, for COM1:, for example. Or for a non-standard port at hex address 3e8 and using IRQ 5, it would be necessary to specify DSZPORT=3e8,5. See DSZ docs for further info as necessary.) WARNING: If you do not SET DSZPORT=SomeCommPort, ZipNews will exit with an error message. The DSZPORT setting is required even if you opt to use a different protocol module. (A future release of ZipNews may allow specification of port and speed via substitutable parameters, such as %1, %2, etc. If DSZ is used with this release, however, capability for handling substitutable parameters is not necessary.) Another required environment variable for the running of ZipNews is the WAFFLE variable. But you're all using that already, right? :) ZipNews requires that the WAFFLE variable be present, but the present release does not actually access your STATIC file. If you're running a multi-node system, there's one last step necessary for reliable operations. Switch to the directory in which you placed ZN.COM and, using the DOS ATTRIB command or other file attribute setting/resetting utility, set the READ ONLY attribute bit ON (write protect). This will prevent SHARE violations during program loading under normal multi-node operations. This completes the installation process. Operating/Using ZipNews ----------------------- There is not much more to say re: operations; ... the first time you fire up ZipNews, it will be pretty obvious how it is used. You should know, however, about the local mode of operation. Here is the command syntax for ZipNews (excluding the registration function described later): zn WaffleAccount [local] If you specify "local" after the WaffleAccount, you may operate the package in a mode simulating that of being online. A ZipNews packet (not compressed) may be created and left in the work directory (specified by "temporary" in the ZN.CFG file). This should prove helpful in testing parts of your setup. Re: advising your users in use of the ZipNews door and its output -- ZipNews' ASCII text format can be viewed quite conveniently using a text viewer such as Vern Buerg's LIST utility. If, for example, you'd like to quickly move from one message to another, set LIST to search for "Subject:". LIST nicely highlights the found line. To search for the next occurrence with LIST, hit the "A" key. To quickly scan to reach the next newsgroup, use "* * <" as the search argument, etc. ZipNews v0.93ß Page 5 Some of your callers might be confused as to what first to do with the news packet received. The source of confusion stems from the use of a characteristic file extension of "ZNS" for the compressed news packet, rather than ZIP or ARC, etc. Most unarchiving utilities will work on a valid archive when supplied the full filename and extension. If a caller has a ZipNews packet created with PKZIP, for example, the unarchiving command would be: PKUNZIP yourbbs.zns (where "yourbbs" represents the name you have selected for the "abbrev" parm in ZN.CFG) Distribution and Restrictions ------------------------------- ZipNews is made available to you as a fully functional package. It is distributed as SHAREWARE. Should you decide to use ZipNews on your system you are obliged to register the product for a fee of $19.95. Registered users are provided support via the BBS mentioned at the end of this documentation OR via e-mail on the Internet. You may use the form ZNORDER.FRM for registering your copy. You are welcome to distribute this package to others so long as it is unmodified and distributed in its entirety, and it is not included or bundled with other goods or services for which a fee is charged. Exceptions are that ZipNews may be distributed by bulletin boards, Internet archive sites, or other information services even though they receive fees to access their downloadable files, or by library services so long as the fee for the diskette on which this package is contained is not more than $6.50. Use of ZipNews beyond a brief evaluation period by individuals, business entities, corporations, and government agencies is prohibited without payment of a registration fee of $19.95 per copy. After You Register ZipNews -------------------------- Once your registration and check have been received, you will be sent a registration number (via U.S. mail OR Internet e-mail, at your option). You may use this number to convert to a registered copy of ZipNews which will eliminate displays of "unregistered", "evaluation copy", etc., and it will insert your name in displays and text files as having duly registered the product. To make a registered copy, invoke ZipNews with the command line parameter of --REGISTER, thusly: zn --register You are prompted to enter your name and your registration number. That's all there is to it. (IMPORTANT NOTE: If you are running a multi-node system and have followed the suggestion of setting the file attribute of ZN.COM to READ ONLY, you will have to set it back to normal before invoking ZN.COM in registration mode. Once you have completed the registration procedure, you should set ZN.COM back to READ ONLY mode.) ZipNews v0.93ß Page 6 Support ------- Support is available to registered users of ZipNews primarily through the main message base of the Northern Lights BBS which can be reached at the number given below. Registration fees may be made payable to: J.C. Kilday Associates P.O. Box 1961 Portland, ME 04104 The author may be contacted at the above address, or via Internet e-mail (jkilday@nlbbs), or through the Northern Lights BBS (address messages to "Sysop") at 207-761-4782. The BBS operates 24 hours, 7 days. Calls accepted at 14400 (v.32bis or VHST) or below.